home *** CD-ROM | disk | FTP | other *** search
/ X User Tools / X User Tools (O'Reilly and Associates)(1994).ISO / sun4c / archive / tcltk.z / tcltk / man / cat3 / DoWhenIdle.3 < prev    next >
Text File  |  1994-09-20  |  3KB  |  133 lines
  1.  
  2.  
  3.  
  4. Tk_DoWhenIdle(3)      Tk Library Procedures
  5.  
  6.  
  7.  
  8. _________________________________________________________________
  9.  
  10. NAME
  11.      Tk_DoWhenIdle, Tk_CancelIdleCall - invoke a  procedure  when
  12.      there are no pending events
  13.  
  14. SYNOPSIS
  15.      #include <tk.h>
  16.  
  17.      Tk_DoWhenIdle(_p_r_o_c, _c_l_i_e_n_t_D_a_t_a)
  18.  
  19.      Tk_CancelIdleCall(_p_r_o_c, _c_l_i_e_n_t_D_a_t_a)                           |
  20.  
  21. ARGUMENTS
  22.      Tk_IdleProc   *_p_r_o_c        (in)      Procedure to invoke.
  23.  
  24.      ClientData    _c_l_i_e_n_t_D_a_t_a   (in)      Arbitrary      one-word
  25.                                           value to pass to _p_r_o_c.
  26. _________________________________________________________________
  27.  
  28.  
  29. DESCRIPTION
  30.      Tk_DoWhenIdle arranges for  _p_r_o_c  to  be  invoked  when  the
  31.      application  becomes idle.  The application is considered to
  32.      be idle when Tk_DoOneEvent has been called, it couldn't find
  33.      any events to handle, and it is about to go to sleep waiting
  34.      for  an  event  to  occur.   At  this  point   all   pending
  35.      Tk_DoWhenIdle  handlers  are  invoked.   For  each  call  to
  36.      Tk_DoWhenIdle there will be a single call  to  _p_r_o_c;   after
  37.      _p_r_o_c  is  invoked  the  handler  is  automatically  removed.
  38.      Tk_DoWhenIdle  is  only  useable  in   programs   that   use
  39.      Tk_DoOneEvent to dispatch events.
  40.  
  41.      _P_r_o_c should have arguments and result that  match  the  type
  42.      Tk_IdleProc:
  43.           typedef void Tk_IdleProc(ClientData _c_l_i_e_n_t_D_a_t_a);
  44.      The _c_l_i_e_n_t_D_a_t_a parameter to _p_r_o_c is a copy of the _c_l_i_e_n_t_D_a_t_a
  45.      argument  given  to  Tk_DoWhenIdle.   Typically,  _c_l_i_e_n_t_D_a_t_a
  46.      points to a data structure  containing  application-specific
  47.      information about what _p_r_o_c should do.
  48.  
  49.      Tk_CancelIdleCall may be used to cancel one or more previous  |
  50.      calls to Tk_DoWhenIdle:  if there is a Tk_DoWhenIdle handler  |
  51.      registered for _p_r_o_c  and  _c_l_i_e_n_t_D_a_t_a,  then  it  is  removed  |
  52.      without  invoking  it.  If there is more than one handler on  |
  53.      the idle list that refers to _p_r_o_c and _c_l_i_e_n_t_D_a_t_a, all of the  |
  54.      handlers  are  removed.   If no existing handlers match _p_r_o_c  |
  55.      and _c_l_i_e_n_t_D_a_t_a then nothing happens.
  56.  
  57.      Tk_DoWhenIdle is most useful in situations where (a) a piece
  58.      of  work  will  have  to  be done but (b) it's possible that
  59.      something will happen in the near future  that  will  change
  60.  
  61.  
  62.  
  63. Tk                                                              1
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. Tk_DoWhenIdle(3)      Tk Library Procedures
  71.  
  72.  
  73.  
  74.      what  has  to  be done, or require something different to be
  75.      done.  Tk_DoWhenIdle allows the actual work to  be  deferred
  76.      until all pending events have been processed.  At this point
  77.      the exact work to be done will presumably be  known  and  it
  78.      can be done exactly once.
  79.  
  80.      For example, Tk_DoWhenIdle might be used  by  an  editor  to
  81.      defer  display  updates until all pending commands have been
  82.      processed.  Without this feature, redundant redisplays might
  83.      occur  in  some situations, such as the processing of a com-
  84.      mand file.
  85.  
  86.  
  87. KEYWORDS
  88.      callback, defer, handler, idle
  89.  
  90.  
  91.  
  92.  
  93.  
  94.  
  95.  
  96.  
  97.  
  98.  
  99.  
  100.  
  101.  
  102.  
  103.  
  104.  
  105.  
  106.  
  107.  
  108.  
  109.  
  110.  
  111.  
  112.  
  113.  
  114.  
  115.  
  116.  
  117.  
  118.  
  119.  
  120.  
  121.  
  122.  
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129. Tk                                                              2
  130.  
  131.  
  132.  
  133.